<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Bootstrapping a cluster | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="modules-discovery.html" title="Discovery and cluster formation">
<link rel="prev" href="modules-discovery-voting.html" title="Voting configurations">
<link rel="next" href="cluster-state-publishing.html" title="Publishing the cluster state">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="setup.html">Set up Elasticsearch</a></span>
»
<span class="breadcrumb-link"><a href="modules-discovery.html">Discovery and cluster formation</a></span>
»
<span class="breadcrumb-node">Bootstrapping a cluster</span>
</div>
<div class="navheader">
<span class="prev">
<a href="modules-discovery-voting.html">« Voting configurations</a>
</span>
<span class="next">
<a href="cluster-state-publishing.html">Publishing the cluster state »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="modules-discovery-bootstrap-cluster"></a>Bootstrapping a cluster<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/discovery/bootstrapping.asciidoc">edit</a>
</h2>
</div></div></div>
<p>Starting an Elasticsearch cluster for the very first time requires the initial
set of <a class="xref" href="modules-node.html#master-node" title="Master-eligible node">master-eligible nodes</a> to be explicitly defined on one or
more of the master-eligible nodes in the cluster. This is known as <em>cluster
bootstrapping</em>. This is only required the first time a cluster starts up: nodes
that have already joined a cluster store this information in their data folder
for use in a <a class="xref" href="restart-upgrade.html" title="Full cluster restart upgrade">full cluster restart</a>, and freshly-started nodes
that are joining a running cluster obtain this information from the cluster’s
elected master.</p>
<p>The initial set of master-eligible nodes is defined in the
<a class="xref" href="discovery-settings.html#initial_master_nodes" title="cluster.initial_master_nodes"><code class="literal">cluster.initial_master_nodes</code> setting</a>. This should be
set to a list containing one of the following items for each master-eligible
node:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The <a class="xref" href="node.name.html" title="node.name">node name</a> of the node.
</li>
<li class="listitem">
The node’s hostname if <code class="literal">node.name</code> is not set, because <code class="literal">node.name</code> defaults
to the node’s hostname. You must use either the fully-qualified hostname or
the bare hostname <a class="xref" href="modules-discovery-bootstrap-cluster.html#modules-discovery-bootstrap-cluster-fqdns">depending on
your system configuration</a>.
</li>
<li class="listitem">
The IP address of the node’s <a class="xref" href="modules-transport.html" title="Transport">publish address</a>, if it is
not possible to use the <code class="literal">node.name</code> of the node. This is normally the IP
address to which <a class="xref" href="modules-network.html#common-network-settings" title="Commonly used network settings"><code class="literal">network.host</code></a> resolves but
<a class="xref" href="modules-network.html#advanced-network-settings" title="Advanced network settings">this can be overridden</a>.
</li>
<li class="listitem">
The IP address and port of the node’s publish address, in the form <code class="literal">IP:PORT</code>,
if it is not possible to use the <code class="literal">node.name</code> of the node and there are
multiple nodes sharing a single IP address.
</li>
</ul>
</div>
<p>When you start a master-eligible node, you can provide this setting on the
command line or in the <code class="literal">elasticsearch.yml</code> file. After the cluster has formed,
this setting is no longer required. It should not be set for master-ineligible
nodes, master-eligible nodes joining an existing cluster, or cluster restarts.</p>
<p>It is technically sufficient to set <code class="literal">cluster.initial_master_nodes</code> on a single
master-eligible node in the cluster, and only to mention that single node in the
setting’s value, but this provides no fault tolerance before the cluster has
fully formed. It is therefore better to bootstrap using at least three
master-eligible nodes, each with a <code class="literal">cluster.initial_master_nodes</code> setting
containing all three nodes.</p>
<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>You must set <code class="literal">cluster.initial_master_nodes</code> to the same list of nodes
on each node on which it is set in order to be sure that only a single cluster
forms during bootstrapping and therefore to avoid the risk of data loss.</p>
</div>
</div>
<p>For a cluster with 3 master-eligible nodes (with <a class="xref" href="node.name.html" title="node.name">node names</a>
<code class="literal">master-a</code>, <code class="literal">master-b</code> and <code class="literal">master-c</code>) the configuration will look as follows:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">cluster.initial_master_nodes:
  - master-a
  - master-b
  - master-c</pre>
</div>
<p>Like all node settings, it is also possible to specify the initial set of master
nodes on the command-line that is used to start Elasticsearch:</p>
<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">$ bin/elasticsearch -Ecluster.initial_master_nodes=master-a,master-b,master-c</pre>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p><a id="modules-discovery-bootstrap-cluster-fqdns"></a> The node names used in the
<code class="literal">cluster.initial_master_nodes</code> list must exactly match the <code class="literal">node.name</code>
properties of the nodes. By default the node name is set to the machine’s
hostname which may or may not be fully-qualified depending on your system
configuration. If each node name is a fully-qualified domain name such as
<code class="literal">master-a.example.com</code> then you must use fully-qualified domain names in the
<code class="literal">cluster.initial_master_nodes</code> list too; conversely if your node names are bare
hostnames (without the <code class="literal">.example.com</code> suffix) then you must use bare hostnames
in the <code class="literal">cluster.initial_master_nodes</code> list. If you use a mix of fully-qualifed
and bare hostnames, or there is some other mismatch between <code class="literal">node.name</code> and
<code class="literal">cluster.initial_master_nodes</code>, then the cluster will not form successfully and
you will see log messages like the following.</p>
<div class="pre_wrapper lang-text">
<pre class="programlisting prettyprint lang-text">[master-a.example.com] master not discovered yet, this node has
not previously joined a bootstrapped (v7+) cluster, and this
node must discover master-eligible nodes [master-a, master-b] to
bootstrap a cluster: have discovered [{master-b.example.com}{...</pre>
</div>
<p>This message shows the node names <code class="literal">master-a.example.com</code> and
<code class="literal">master-b.example.com</code> as well as the <code class="literal">cluster.initial_master_nodes</code> entries
<code class="literal">master-a</code> and <code class="literal">master-b</code>, and it is clear from this message that they do not
match exactly.</p>
</div>
</div>
<h4>
<a id="_choosing_a_cluster_name"></a>Choosing a cluster name<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/discovery/bootstrapping.asciidoc">edit</a>
</h4>
<p>The <a class="xref" href="cluster.name.html" title="cluster.name"><code class="literal">cluster.name</code></a> setting enables you to create multiple
clusters which are separated from each other. Nodes verify that they agree on
their cluster name when they first connect to each other, and Elasticsearch
will only form a cluster from nodes that all have the same cluster name. The
default value for the cluster name is <code class="literal">elasticsearch</code>, but it is recommended to
change this to reflect the logical name of the cluster.</p>
<h4>
<a id="_auto_bootstrapping_in_development_mode"></a>Auto-bootstrapping in development mode<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/discovery/bootstrapping.asciidoc">edit</a>
</h4>
<p>If the cluster is running with a completely default configuration then it will
automatically bootstrap a cluster based on the nodes that could be discovered to
be running on the same host within a short time after startup. This means that
by default it is possible to start up several nodes on a single machine and have
them automatically form a cluster which is very useful for development
environments and experimentation.  However, since nodes may not always
successfully discover each other quickly enough this automatic bootstrapping
cannot be relied upon and cannot be used in production deployments.</p>
<p>If any of the following settings are configured then auto-bootstrapping will not
take place, and you must configure <code class="literal">cluster.initial_master_nodes</code> as described
in the <a class="xref" href="modules-discovery-bootstrap-cluster.html" title="Bootstrapping a cluster">section on cluster bootstrapping</a>:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">discovery.seed_providers</code>
</li>
<li class="listitem">
<code class="literal">discovery.seed_hosts</code>
</li>
<li class="listitem">
<code class="literal">cluster.initial_master_nodes</code>
</li>
</ul>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p><a id="modules-discovery-bootstrap-cluster-joining"></a> If you start an Elasticsearch node
without configuring these settings then it will start up in development mode and
auto-bootstrap itself into a new cluster. If you start some Elasticsearch nodes on
different hosts then by default they will not discover each other and will form
a different cluster on each host. Elasticsearch will not merge separate clusters together
after they have formed, even if you subsequently try and configure all the nodes
into a single cluster. This is because there is no way to merge these separate
clusters together without a risk of data loss. You can tell that you have formed
separate clusters by checking the cluster UUID reported by <code class="literal">GET /</code> on each node.
If you intended to form a single cluster then you should start again:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Shut down all the nodes.
</li>
<li class="listitem">
Completely wipe each node by deleting the contents of their
<a class="xref" href="modules-node.html#data-path" title="path.data">data folders</a>.
</li>
<li class="listitem">
Configure <code class="literal">cluster.initial_master_nodes</code> as described above.
</li>
<li class="listitem">
Restart all the nodes and verify that they have formed a single cluster.
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="navfooter">
<span class="prev">
<a href="modules-discovery-voting.html">« Voting configurations</a>
</span>
<span class="next">
<a href="cluster-state-publishing.html">Publishing the cluster state »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
